home *** CD-ROM | disk | FTP | other *** search
/ Mac Format 1995 June / MacFormat 25.iso / Shareware City / Developers / fortran-to-c-translator-11 / Mac F2C 1.1 / Mac F2C Documentation / INSTRUCTIONS (CodeWarrior) < prev    next >
Text File  |  1995-01-30  |  14KB  |  326 lines
  1.         *************************************************
  2.         *************************************************
  3.  
  4.           INSTRUCTIONS FOR SETTING UP AND USING Mac F2C 
  5.  
  6.                    WITH METROWERKS CODEWARRIOR C
  7.  
  8.         *************************************************
  9.         *************************************************
  10.  
  11.  
  12.  
  13. Before you can use the code produced by Mac F2C, you must set up and build 
  14. all of the required support libraries.  There are also special rules that 
  15. must be followed when using code produced by Mac F2C.  The process and 
  16. rules are slightly different for Symantec's THINK C and for Metrowerks' 
  17. CodeWarrior.  These instructions are for setting up Mac F2C for use with 
  18. Metrowerks CodeWarrior.  Refer to the documentation file "Instructions 
  19. (THINK)" for instructions on how to set things up for use with Symantec 
  20. THINK C.
  21.  
  22. Users upgrading from previous versions of Mac F2C need to re-install ALL 
  23. library source code, including main.c and f2c.h.  Version 1.1 source code 
  24. is now fully compatible with CodeWarrior and CodeWarrior project files are 
  25. included for the libraries and as models for using Mac F2C generated code.
  26.  
  27. Please note that the source code and libraries provided are set up to use 
  28. with CodeWarrior release 5.  To use earlier CodeWarrior releases with Mac 
  29. F2C, contact Dirk Froehling (dirk@gaga.maschinenbau.uni-dortmund.de), 
  30. because a few workarounds and additions are required.
  31.  
  32. The instructions here are broken into four sections:
  33.  
  34.     A.  Setting up Mac F2C
  35.     
  36.     B.  Verifying correct operation
  37.     
  38.     C.  Translating with Mac F2C
  39.     
  40.     D.  Using C code produced by Mac F2C
  41.     
  42.     
  43.     
  44. *****************************************************************************
  45.  
  46.  
  47. A.  SETTING UP Mac F2C
  48. **********************
  49.  
  50. Step 1:  BRING ALL THE LIBRARIES UP-TO-DATE
  51.  
  52. The libraries of the Mac F2C distribution come without binaries, so you have
  53. to build them according to the following algorithm. There are two versions
  54. of each library project, one for the 68K compiler and one for the PowerPC
  55. compiler. They are named with the usual extensions, 68K.µ and PPC.µ. You can
  56. use both versions or just one if you like (skip the instructions for either
  57. the 68K or PPC version).
  58.  
  59. FOR the project files:
  60.  
  61.         (1) "libI77.68K.µ"  in the "Mac F2C Libraries" folder
  62.         (2) "libF77.68K.µ"  in the "Mac F2C Libraries" folder
  63.         (3) "libI77.PPC.µ"  in the "Mac F2C Libraries" folder
  64.         (4) "libF77.PPC.µ"  in the "Mac F2C Libraries" folder
  65.         
  66. REPEAT the following steps:
  67.  
  68.     (a) Double-click on the project file.  
  69.     
  70.     (b) In the CW Environment's "Project" menu, select the 
  71.         "Make" command.  
  72.  
  73. END REPEAT
  74.  
  75.  
  76.  
  77. Step 2:  MOVE THINGS TO THE RECOMMENDED LOCATIONS
  78.  
  79. For easiest and smoothest operation, the support libraries and other 
  80. support files should be installed where the CodeWarrior C compiler can find 
  81. them easily.  I recommend you install Mac F2C libraries and support files 
  82. as follows:
  83.  
  84. (1) Drag the libraries "libI77.68K", "libF77.68K", "libI77.PPC" and
  85.     "libF77.PPC" you obtained by following the instructions of Step 1
  86.     from the folder "Mac F2C Libraries" to the folder "Metrowerks  C/C++ ƒ"
  87.     folder that contains the CodeWarrior C/C++ Environment.  You can put 
  88.     them into a folder inside the "Metrowerks C/C++ ƒ" folder if you 
  89.     prefer.  You can delete the THINK files "libF77", "libI77a", and 
  90.     "libI77b" in the folder "Mac F2C Libraries" if you don't need them.
  91.     
  92. (2) The "For '(Project Stationary)'" located in the "CodeWarrior Specific 
  93.     Stuff" folder contains project stationary files that are used for 
  94.     compiling C code produced by Mac F2C.  Drag the project stationary 
  95.     files to the "(Project Stationary)" folder found in the "Metrowerks 
  96.     C/C++ ƒ" folder that contains the CodeWarrior C/C++ Environment.
  97.  
  98. (3) The "For 'Metrowerks C/C++ ƒ'" located in the "CodeWarrior Specific 
  99.     Stuff" folder contains code files ("f2c.h" and "main.c") that are 
  100.     needed to run C programs produced by Mac F2C.  Drag these two files to 
  101.     the "Metrowerks C/C++ ƒ" folder that contains the CodeWarrior C/C++ 
  102.     Environment.  You can put them into a folder inside the "Metrowerks 
  103.     C/C++ ƒ" folder if you prefer.
  104.  
  105.  
  106.  
  107.  
  108.  
  109. *****************************************************************************
  110.  
  111.  
  112. B.  VERIFYING CORRECT OPERATION OF Mac F2C
  113. ******************************************
  114.  
  115. The folder "Test Project ƒ" contains the following files:
  116.  
  117. (1) "test.f" -- a sample FORTRAN program.
  118.  
  119. (2) "main.c" -- the main program required to run programs produced
  120.     by with Mac F2C.
  121.     
  122. (3) "f2c.h" -- an include file required to compile programs produced by 
  123.     Mac F2C.
  124.  
  125. (4) "test.c (Output)" -- what you should get when you translate 
  126.     the sample FORTRAN code files.
  127.     
  128. (5) "Test.68K.µ" and "Test.PPC.µ" -- CodeWarrior projects to run the sample
  129.     program. These will serve as models for how to compile, link, and run 
  130.     programs translated by F2C. 
  131.     
  132. (6) "Test.π" and "Test++.π" -- THINK project files (not used)
  133.     
  134. Translate the sample FORTRAN program "Test.f" simply by dragging it onto 
  135. Mac F2C.  Do not change any of the options (use "Factory Defaults").  Once 
  136. you have done this you can compare it with "Test.c (sample)" file to verify 
  137. that you got the same thing.  If so, double click on the CodeWarrior 
  138. project "Test.68K.µ" or "Test.PPC.µ" and follow the same steps outlined in 
  139. the "Bringing Libraries Up-To-Date" section to bring the test project 
  140. up-to-date.  Run it to verify correct operation.
  141.  
  142.  
  143.  
  144. *****************************************************************************
  145.  
  146.  
  147. C.  TRANSLATING FORTRAN PROGRAMS
  148. ********************************
  149.  
  150. You can use Mac F2C to translate FORTRAN to C using four methods:
  151.  
  152. (a) Start up Mac F2C and select the "Translate" command in the File menu.  
  153.     
  154. (b) Drag-&-drop a bunch of FORTRAN files onto Mac F2C.
  155.  
  156. (c) Use a scripting language (e.g., AppleScript) to send Mac F2C either an 
  157.     'open' command, an 'f2c' command, or a 'translate' command.  For more 
  158.     information on driving Mac F2C from a script see the instructions in 
  159.     the folder "Mac F2C AppleEvents".
  160.  
  161. (d) Use the MPW/Toolserver tools provided in the "MPW/Toolserver Tools"
  162.     folder inside the "CodeWarrior Specific Stuff" folder.  Please follow 
  163.     the instructions in the "Toolserver READ ME" file.
  164.      
  165. FORTRAN files must be TEXT files and *must* end in ".f" or ".F" (sorry, but 
  166. the ending is determined by the unix f2c kernel -- it rejects files handed 
  167. to it with any other endings).  The output file is the same name with a 
  168. ".c" extension if you selected C code for the output, or the same name with 
  169. a ".cp" extension if you selected C++ code for the output.
  170.  
  171. The first five items in the Options menu let you control the various 
  172. translation and code generation options.  If you check the "Make these the 
  173. new defaults" box before clicking the "OK" button, your option selections 
  174. will be saved in a Preference file and used again the next time you start 
  175. Mac F2C.
  176.  
  177. If you do not understand what an option means, check the balloon help.  The 
  178. help balloons provide more detailed explanations of what each option means.  
  179. They also explain why dimmed options are not available and what you can do 
  180. to make them available.
  181.  
  182. The last item in the Options menu ("Mac F2C Preferences…") lets you control 
  183. how Mac F2C operates.  This dialog lets you control:
  184.  
  185.     - How Mac F2C behaves after having been launched with a drag-&-drop.
  186.     
  187.     - Whether the "Advanced Options" dialog will have an edit text field 
  188.       that allows you to enter unix option switches directly.
  189.       
  190.     - The creator type for all of the output files (determines their icon).
  191.     
  192.     - Whether and how Mac F2C interacts with THINK and/or CodeWarrior.  If 
  193.       the notify option is checked, Mac F2C will attempt to touch the 
  194.       corresponding THINK or CodeWarrior project file after translating a 
  195.       FORTRAN file into C successfully.  If THINK/CodeWarrior is not running 
  196.       or if the file is not part of the current project, Mac F2C will fail 
  197.       silently.  If the make option is checked, then Mac F2C will also send 
  198.       a make (e.g., bring up to date) command to THINK/CodeWarrior.  If a 
  199.       group of FORTRAN files are translated at once (via a drag-&-drop or 
  200.       via an AppleScript), the make command is not sent until the last file 
  201.       is translated.  Again, Mac F2C fails silently if THINK or CodeWarrior 
  202.       can't do it.
  203.       
  204. As in the case of the other option dialogs, check the balloon help if you 
  205. do not understand what an option means.  
  206.        
  207.  
  208.  
  209.  
  210. *****************************************************************************
  211.  
  212.  
  213. D.  USING C CODE PRODUCED BY MAC F2C
  214. ************************************
  215.  
  216. The C code produced by Mac F2C has the following compile and link requirements:
  217.  
  218. 68K version:
  219.  
  220.     -   the header file "f2c.h"
  221.     -   the F2C libraries "libI77.68K" and "libF77.68K"
  222.     -   the CW libraries "ANSI (4i/8d) C.68K.Lib", "MathLib68K (4i/8d).Lib",
  223.         "SIOUX.68K.Lib", and "MacOS.lib"
  224.     -   4-byte integers
  225.     -   8-byte doubles
  226.     -   far data
  227.     -   "Smart" code model
  228.  
  229.  
  230. PPC version:
  231.  
  232.     -   the header file "f2c.h"
  233.     -   the F2C libraries "libI77.PPC" and "libF77.PPC"
  234.     -   the CW libraries "ANSI C.PPC.Lib", "MWCRuntime.Lib", "Interface.Lib",
  235.         "SIOUX.PPC.Lib", and "MathLib"
  236.     
  237. In addition, if you compile a stand-alone FORTRAN program (vice only some 
  238. FORTRAN subroutines) you must include "main.c" in your project.  This is 
  239. because the original main routine in the FORTRAN program becomes a function 
  240. that is called by main.c.  In addition, main.c performs a series of 
  241. initializations (primarily related to error catching) prior to executing 
  242. the main FORTRAN program.
  243.  
  244. The "For '(Project Stationary)'" and "For 'Metrowerks C/C++ ƒ'" folders 
  245. provided in the "CodeWarrior Specific Stuff" folder contain everything you 
  246. need to compile and run code produced by Mac F2C.  Copy the project 
  247. stationary files to the "(Project Stationary)" folder, and copy main.c and 
  248. f2c.h to the "Metrowerks C/C++ ƒ" folder or to a folder inside the 
  249. "Metrowerks C/C++ ƒ" folder.  To start a new project using Mac F2C code, 
  250. launch the CW 68K or PPC C compiler, select "New Project..." and choose the 
  251. Mac F2C project stationary, a name and a folder for your project in the 
  252. upcoming Standard File dialog.  Then add your code files and bring 
  253. everything up-to-date.
  254.  
  255. If you compile a FORTRAN subroutine or function that you want to call from 
  256. a C program, look at the output C code to see the appropriate calling 
  257. protocol.  You may or may not need to include the F2C support libraries 
  258. (libF77 and libI77).  In rare cases, you may also need to copy 
  259. some of the initialization code from "main.c" to your calling program.
  260.  
  261.  
  262. Please read the following section carefully if you intend to use Mac F2C
  263. with the 68K compiler (the PPC compiler doesn't give you any of the options
  264. mentioned, so there is nothing to consider):
  265.  
  266. As noted above, code produced by Mac F2C *MUST* be compiled with 4-byte 
  267. integers.  This requirement cannot be relaxed.  The other requirements 
  268. (8-byte doubles, far data) can sometimes be relaxed:
  269.  
  270.     -   IF you do not use doubles in any situation where their size 
  271.         relative to reals matters (e.g., if you do not use doubles in 
  272.         equivalence and common statements), then your code probably does
  273.         not require 8-byte doubles.  You need to verify this on a case-
  274.         by-case basis.
  275.         
  276.         This requirement exists because Mac F2C follows FORTRAN sizing 
  277.         rules when compiling FORTRAN code:  sizeof(real) == sizeof(integer) 
  278.         and sizeof(double) == 2*sizeof(real).  FORTRAN real is compiled as 
  279.         C float and FORTRAN double as C double, so doubles have to be 
  280.         8-bytes long for equivalence and common statements to be properly 
  281.         aligned.  There are a few other cases where the size of double 
  282.         variables matters; see AT&T Computing Science Technical Report 
  283.         No. 149 (included with Mac F2C) for a detailed discussion.
  284.         
  285.     -   IF you compile your program with the option "Local variables are 
  286.         automatic" and you do not have large static data structures, you 
  287.         *might* not need "Far Data".  You need to verify this on a case-
  288.         by-case basis.
  289.         
  290.         Mac F2C creates large static data structures for I/O.  If you create 
  291.         local variables in the global area (static vice automatic) or if you 
  292.         have other static data, you will almost certainly require "Far Data".  
  293.         The I/O data structures can be large enough that you may require "Far 
  294.         Data" for that reason alone.  
  295.  
  296.     -   The 68K project files are all set to use the "Smart" code model. That
  297.         means, the compiler generates a combination of the far and near (32 bit
  298.         and 16 bit) addressing types, using near when possible. Segments are
  299.         not limited to 32K of object code.
  300.         
  301.         I suggest to stick with this option, since the "Large" code model doesn't
  302.         give you any advantage over "Smart", and "Small" requires a jump table
  303.         for inter-segment jumps which has a negative effect on code size and
  304.         speed. But you can try and put all files into one segment if your program
  305.         is small enough and doesn't use much of the library code. You need to
  306.         verify this on a case-by-case basis.       
  307.         
  308. If you change the "8-byte doubles", "Smart", "Far Data" or "68881" options, 
  309. remember to also change them in all the Mac F2C libraries, specifically 
  310. "libI77.68K" and "libF77.68K", and include the appropriate ANSI library.  
  311. The standard ANSI library used in the F2C project files is "ANSI (4i/8d) 
  312. C.68K.Lib".  The arguments inside the braces show the compiler options 
  313. (4-byte integers/ 8-byte doubles).  If you don't need 8-byte doubles, use 
  314. "ANSI (4i) C.68K.Lib", if you want direct 68881 support, use "ANSI 
  315. (4i/F/8d) C.68K.Lib", for example.
  316.  
  317.  
  318. I urge all users to read the enclosed AT&T Computing Science Technical 
  319. Report No. 149.  Consider it your compiler and language reference 
  320. manual.  You can print the report by downloading it to any PostScript 
  321. printer.  You can use Apple's LaserWriter Utility application to do 
  322. this or you can use any of the many equivalent utilities.
  323.  
  324.  
  325.  
  326.